Thank you for taking the trouble to try this program out. We hope you like it.
Note: this file is formatted and is best read with SimpleText and not TeachText.
Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please donユt modify this file or distribute modified versions.
Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures donユt appear, you can make them appear by scrolling up a page and then back down a page.
This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed.
Contents
The documentation for IIe comes in 4 files. Their contents are:
1. Read me first
What is it? - description, features, requirements, compatibilty, and performance issues
Description
Features
Hardware and software requirements
Compatibility
Performance issues
Installation and setup
Simple installation/setup
Tips
Frequently Asked Questions (FAQ)
2. Instructions
The Apple //e window
The display area
The //e screen
The icon buttons
Function keys
Graphics modes
Disk inserting/removing
Using real disks
Using disk images
How to insert and remove disks and disk images
Loading and saving information - memory images
Emulator instructions
Default settings
Starting up the emulator
The Reset key
The Keyboard
Paddles and buttons
Debugger instructions
3. Configuring IIe
General pane
65c02 pane
Memory pane
Video pane
Sound pane
Keyboard pane
Input devices pane
Disks pane
Slots pane
4. Other stuff
Cost/fee and registration
Version history
Future version features
Distribution
Contacting the author
Other software by Vincent
Disclaimer
1. Read me first
Itユs best to begin with a word of warning:
IIe is a complex program and has some powerful features. You can easily lose Apple //e data by using this program メrecklesslyモ so please do these two things:
(1) make a backup of all your important data and disk images, and
(2) read these documents thoroughly. By reading these documents, youユll understand how IIe works and how to use it safely and usefully.
You can disregard this warning to your own consequence. It will be pointless to complain to me that you lost your work. My reply will be: why didnユt you read the instructions and make a backup? Of course I want IIe to work as reliably and as safely as a real //e would. Nevertheless, there are probably some minor bugs in this program, so itユs best to be safe and always have a backup.
OK, that out the way, letユs define some of the terms used below before getting started. The term メIIeモ refers to this Mac program. In contrast, the term メ//eモ refers to the virtual Apple //e that you use in the メApple //eモ window, ie the virtual computer and not the Mac program and its menus, windows, dialogs, etc. Donユt worry. Itユll make more sense as you read along.
If you insist on reading the very minimum, you should at least peruse the Frequently Asked Questions which are at the bottom of this document.
What is it? - description, features, requirements, compatibilty, and performance issues
Description:
IIe is an Apple //e emulator for Macintoshes and PowerMacintoshes. It lets you run virtually any program for the Apple II, Apple II Plus, Apple //e, and Apple //c computers. It does not run Apple IIgs software.
It has been tested with a limited number of programs and works well with them. Most of the Apple II OSes boot up, including DOS 3.3, ProDOS 2.0.3, and Apple Pascal 1.2. Most games will work without problems. See below for more details about this versionユs abilities and limitations.
How does it work? IIe takes machine instructions written originally for the 65c02 microprocessor and emulates them in software. In other words, it uses the CPU in your Mac to do the work that was originally intended for a 65c02 microprocessor. The emulator keeps track of the 65c02 instructions, registers and memory usage, as well as converting the memory used for graphics or text into Macintosh graphics. As well, Apple II peripherals such as the Disk II (5 1/4" disk drive), and the UniDisk for 3 1/2" floppy disks are also emulated.
The goals of this version are functionality, compatibility, versatility, a decent feature set, and decent emulation speed on high end 68030s or better.
Features:
・ comes as a メfat binaryモ - that is, it contains both 680x0 and PowerPC code for optimal performance on any Mac. This version performs quite well on 68040 Macs and PowerMacs and performs メdecentlyモ on 68030 Macs. 68040 Macs should get 1Mhz //e performance. PowerMacs should be able to get 2MHz //e performance or better.
・ able to display an Apple //e computer in a Mac window. This version supports all the //e graphics modes: text, lores graphics, double lores graphics, hires graphics, and double hires graphics. It even flashes text. The normal and alternate (メMouseTextモ) character sets are supported. The hires and double hires graphics can be displayed in monochrome or colour. Text and hires graphics displayed in monochrome mode can be displayed in a variety of monochrome colours such as white, green or amber (read that sentence twice if you didnユt get it the first time)
・ able to take keystrokes on your Mac keyboard and pass them to the emulated //e. Supports the メopenモ (command) and メclosedモ (option) apple keys on the //e keyboard (as well as the third paddle button by the shift key - known as the メshift key modificationモ).
・ the //e can be reset from your Mac keyboard (by pressing control-delete)
・ able to read 5 1/4" disk and 3 1/2" disk images - this version supports all common image formats including 5 1/4" nibble images
・ able to read directly from a 3 1/2" disk in the internal drive on your Mac and use it as a 3 1/2" disk in the emulator
・ able to use a ProDOS partition of your hard disk as a ProDOS hard disk in the emulator. You can set up such a partition with メApple HD Setupモ or メFWB Hard Disk Toolkitモ.
・ able to directly read from or write to files in a Mac directory from any ProDOS program. This is a very handy feature and allows direct transfer of data without the need for PC Exchange
・ supports fast reads and writes on Dos 3.3 and ProDOS 5 1/4" disks
・ able to switch any disk in any drive at any time
・ emulates a joystick by using the keypad on your Mac keyboard or the mouse
・ emulates a RamWorks III RAM disk
・ emulates peripherals such as a ThunderClock clock card, the AppleMouse mouse card and the Apple II Memory Expansion memory card
・ very configurable via an easy-to-use preferences and setup dialog
・ supports Apple //e speaker sounds
・ has a useful debugger to allow you to set breakpoints, inspect registers, etc. if you want to debug Apple II programs
Hardware and software requirements:
IIe requires:
・ a colour-capable Macintosh (ie, not the Mac Plus, SE, Portable, or PowerBook 100). A fast 68030 Mac is the minimal hardware you should run IIe on
・ a 13" or 14" colour monitor (or larger)
・ System 7 or later
・ the Thread Manager (which is built into System 7.5 or later).
・ Sound Manger 3.0 or later.
Recommended:
・ a fast 68040 Mac or a PowerMac
・ support for 256 colours
・ System 7.5.1 or later
・ Sound Manger 3.1 if you have a PowerPC Mac
・ Thread Manger 2.1 if you have a PowerPC Mac
・ a ProDOS partition on your Mac hard disk (created with Appleユs HD Setup program or a third party utility such as FWBユs Hard Disk Toolkit).
Compatibility:
This software has been tested on systems 7.1 to 7.5.1.
Currently there are no known software conflicts. If you should find a problem, let me know.
With regard to Apple II software, there are some programs (especially some games) that use and even rely on illegal 6502 instructions to properly work. They wonユt work with IIe because IIe does not emulate illegal instructions. If I have the time and the energy, I may try to get these instructions in but that isnユt a promise.
Performance issues:
This version does not allow background programs much background time to run so you may find print jobs tend to slow down and modem downloads donユt work well. Similarly, programs that take up background time will tend to slow down the emulator (because your Macユs CPU spends less time running the emulator). Even having a lot of other programs open will slow down the emulator - merely closing those other 6 apps will bring a noticable speedup in the program.
For best performance:
・ close all unecessary programs
・ reduce the number of extensions you install at startup
・ run IIe in Black & White mode (ie, 1-bit mode) - the fastest graphics blitters are the 1-bit blitters because they have the smallest amount of memory to blit
・ use the small window size
・ use direct drawing
Installation and setup
Simple installation/setup
To install and set up this program:
1) decompress the archive that this program comes in. Youユve probably already done this to be able to read this Read Me.
2) get a copy of the Apple //e ROMs*. If youユre on the internet, you can get it from:
If youユre on an online service, use its ftp ability to obtain the above file.
Use a utility such as メDropStuff with StuffIt Expanderモ or メZipItモ to decompress the file.
*For legal reasons, the ROMs cannot be distributed with this emulator because they are the copyright of Apple Computer, Inc. メSo what?モ you might ask. Well, I personally donユt enjoy getting letters from lawyers, and since I still own an Apple //e (and it still works just fine thanks), I have all the ROMs I need (well, almost all: if only Iユd bought that mouse card, memory card, serial card, etc. etc. when I could have...).
If you donユt have internet access but do have a real Enhanced //e*, you can follow these instructions to create your copy of the ROMs. You will need some way of transferring the file to your Mac such as a 3 1/2" floppy disk or some kind of serial connection. Ask your nearby user group for info about how to do this.
Note that in the following lines, the ヤ0ユ character is a zero, and that anything between angled brackets ヤ<ユ or ヤ>ユ is one character - eg, <control-C> means hold down the control key and then press the C key (which is an invisible character).
a) start up your //e and boot up ProDOS. Then run BASIC.SYSTEM to enter Applesoft Basic (it will display a ヤ]ユ prompt)
b) type メcall-151<return>モ to enter the //eユs monitor program (it will then display the ヤ*ユ prompt)
c) type メ2000<D000.FFFFM<return>モ
d) type メC007:0<return>モ
e) type メ5100<C100.CFFEM<return>モ
f) type メC006:0<return>モ
g) type メ<control-C><return>モ to re-enter Basic
h) type メBSAVE APPLE2E.ROM,A$1000,L$5000モ
i) transfer this file to your Mac as a binary file
* Enhanced //eユs have a 65c02 processor and when you run programs like AppleWorks, they will display folders and characters such as the open and closed apples on the text screen. Unenhanced //eユs have a 6502A processor and donユt have the special characters so AppleWorks ヤlooks funnyユ.
3) make sure the ROM file is called メAPPLE2E.ROMモ and that it is in the same folder as IIe. If you want to see the icon for ROMs, change the type/creator of the file to ヤROMsユ/ヤAIIeユ.
4) set IIeユs memory size. IIeユs memory size is preset at 1600K (it will appear as 1942K on PowerPC Macs with virtual memory off), which is optimal for 68K Macs using a 256K table which helps the emulator run faster. You can change this setting depending on what kind of Mac you have and whether you want to use the table:
・ if you have a PowerPC Mac, you can set IIeユs memory size to 1200K if you have virtual memory on (or if you have RamDoubler on), or to 1542K if you have virtual memory off. If you set IIe to use more memory in the form of RAM disks, etc. then of course youユll have to use large values (depending on the size of your extra memory requirements).
・ if you have a 680x0 Mac and set IIe to not use the 256K table, then you can reduce IIeユs memory size to 1350K. DO NOT set IIe to any value below 1350K or it may crash or behave erratically.
You are now set to use IIe. Read the information below and in the following documents to learn how to properly use it.
Tips
・ changing the creator of a disk image to ヤAIIeユ allows you to double click the file to have IIe use it
・ clicking the Mono/colour icon button changes the display from monochrome to colour and vice versa
・ control-clicking the Mono/colour icon button changes the colour of the monochrome text/graphics
・ option-clicking the Mono/colour icon button changes the screenユs bit depth from 8 -> 1 -> 4 -> 8, etc.
・ control-esc or F15 will start/stop the emulator
・ be sure to have backups of your Apple II disks because IIe can destroy the disks as easily as a real //e can! When you delete a file on your disk (or disk image), itユs gone! You may be able to recover it with a disk utility program but itユs much better (and a whole lot saner) to have a backup and restore it from that
Frequently Asked Questions (FAQ)
Q: The program complains about not being able to find a file called メAPPLE2E.ROMモ. What gives?
A: IIe does not contains the Apple //e ROMs because they are copyrighted material. You will need to either dump your own ROMs or get a copy of the ROMs that have already been dumped. See the section メInstallation and Setupモ above for more info about obtaining them. Note that legally you cannot use the ROM file specified above unless you own an Apple //e.
Q: When I double click IIe, it starts up and then stops and Iユm left back in the Finder. Whatユs going on?
A: There was a problem during IIeユs startup. The most likely causes are: Thread Manager not present or installed, out of memory, and corrupted preferences. Install Thread Manager if you are running a system prior to System 7.5. Try giving IIe more memory. Try deleting the preferences.
Q: The program starts up but then nothing happens. Whatユs wrong?
A: When you start up IIe without any disks loaded into the drives, the //e is halted until a disk is inserted and the On/Off or Go/Stop icon is clicked.
Q: IIe starts up but then crashes/freezes/hangs/bombs/dies/stops working. Help!
A: Try these tips in the order shown:
1) restart with all extensions off by holding down the shift key until your Mac says メWelcome to Macintosh. Extensions Off.モ. If this works, then one of your extensions is conflicting with IIe. If you find out which one it is, let me know (send email) and Iユll try to fix it.
2) give IIe more memory
3) turn off (uncheck) the メDirect drawingモ option in the video pane of the preferences. Some Mac video cards donユt like this option when itユs on (checked).
4) install a new copy of IIe and delete the メIIe Preferencesモ file in your Preferences Folder (which is in your System Folder)
5) contact me with a detailed description of the problem and how to reproduce it. One request: you do not need to give me a 10 page list of your extensions; it usually is not helpful. If I need such a list, Iユll ask you for it.
Q: It runs too slowly! Help!
A: try these suggestions in the order shown:
1) use the small window mode if you can
2) change to Black and White mode if your Macユs video system supports it
3) change the video frequency to 20Hz instead of 30Hz or 60Hz
4) turn on direct drawing
5) increase the CPU speed in the 65c02 pane of the preferences
6) quit all other programs
7) turn off all unecessary extensions, including File Sharing, AppleTalk, Virtual Memory, etc., etc.
8) get a faster machine (sorry but thereユs a limit to how fast any Mac can operate!)
Q: Talking of speed, why isnユt IIe as fast as StopTheMadness on my 680x0 Mac?
A: IIe emulates an Apple //e and therefore requires a much more complicated memory scheme than StopTheMadness, which emulates an Apple II+. The price of being able to properly use 128K of Apple //e memory (or more) is that the emulator has to do more work to correctly access the memory. Result: slower performance than STM but more flexible and more powerful memory use.
Q: Talking of emulators, why isnユt IIe an Apple IIgs emulator? Are there plans for this?
A: IIe was designed to emulate an Apple //e. Emulating an Apple IIgs is a lot more work and a much harder task. I have no plans for doing this and it is very unlikely I ever will. Instead, I recommend obtaining the FAQ of the internet newsgroup comp.emulators.apple2. There is mention in that document of the IIgs emulators currently in development (and yes, itユs written for Macs).
Q: Some of the sounds that IIe makes donユt sound right. What gives?
A: Emulating the Apple //e speaker is one of the hardest things to do right. IIe tries its best but may not always succeed. There isnユt much that can be done about it. Most programs will sound OK and only a few will have problems. Choppy sounds may be due to too frequent video drawing or your Macユs CPU being too slow. Slower Macs may not produce continuous sound - sorry, but they just donユt have enough CPU speed to do it. Try these suggestions:
1) try using 30Hz or 20Hz instead of 60Hz (see the video pane in the preferences)
2) use the smaller screen
3) use direct drawing (see the video pane in the preferences)
4) turn off as many extensions as you can
5) turn off any networking software you can
6) quit as many programs as you can (and not just close their windows)
7) get a faster Mac (well I had to mention this option, didnユt I?)
Q: What do the numbers at the top of the window mean? What do the red circles and squares mean?
A: These are the drive lights and slot/drive indicators. When an Apple II program accesses the disk, the lights go on to tell you what is happening. You can click them to change the type of displayed lights (but clicking has no other effect on the program).
Q: The //e program Iユm running suddenly stops, then a window labelled メ6502 Debuggerモ comes up and itユs full of gibberish! What on earth is going on?
A: Your //e program has come across a メbreakモ instruction or an illegal instruction (or it has reached a breakpoint that was previously set). The most common reasons for this are: a buggy program or a //e conflict (eg, the program youユre using doesnユt like the Clock card in slot 2). This situation is analogous to your Mac displaying the dreaded メbombモ dialog: the CPU is stuck at a place it canユt continue onwards from. Itユs fairly unlikely youユll be able to continue the //e program and save any data but you may want to try: click the メSkipモ button to skip over the illegal instruction. If it works, save your file and reboot the //e to start it up in a メcleanモ state. To exclude a //e conflict, remove all unneeded メcardsモ from their メslotsモ.
Of course, if you ended up in the debugger because of a breakpoint (itユll say so in the bottom left corner of the window) then just clear the breakpoints and click the メRunモ button.
Q: What does the Interrupt icon do?
A: This halts the //eユs CPU and puts you into the 6502 debugger. From here, you can set breakpoints and follow the code as it is emulated. To exit the debugger, click the Run button (but remember to clear the breakpoints).
Most people wonユt need to ever use this button. You will need to know the 65c02 instruction set to make sense of the 6502 Debugger window.
Q: Why is it that when I select a menu command with the mouse it works fine, but when I use the keyboard shortcut for that command then instead of doing anything, I get the key in the //e window?
A: when the //e emulator is running, all keystrokes are directed to the emulator window and menu commands are not interpreted. This is so that AppleWorks, Multiscribe and other programs which use メcommand-<key>モ combinations will function correctly. To access the menu commands from the keyboard, first halt the emulator by clicking the メGo/Stopモ icon or using the メGo/Stop //eモ menu command in the File menu, then select your desired command, and then run the emulator by using the メGo/Stopモ icon again.
Notes:
(i) if the メGo/Stopモ icon or command is set up to function as an On/Off switch, then instead of halting the emulator, the icon will switch off the emulator and you will lose all of the contents of the //eユs memory without any warning that this will occur. Be careful with this option!
(ii) if you have an extended keyboard, you can use the function keys to do many of the same functions that the menu commands do, and you donユt need to halt the emulator to use them. Therefore, it is much easier to use the function keys if you can. See the file メ2. Instructionsモ for details on what the function keys do.
Q: How much memory should I set IIe to use?
A: See the Installation and setup section above for a detailed answer. The メcatch allモ answer is 1600K, but it will need to be more if you set up IIe to use a RAM disk, etc.
Q: I changed the memory settings in the preferences but nothing happens. Whatユs going on?
A: Changes to the memory settings wonユt occur until IIe is restarted. Hereユs how to change IIeユs memory settings:
1) change the settings in the Memory pane in the IIe Preferences window and click the OK button
2) select Quit IIe from the File menu
3) increase or decrease IIeユs memory requirements in the Finderユs Get Info window
4) close the Get Info window
5) double click the IIe icon. IIe will then start up with the new memory settings.
Q: I changed the slot settings in the preferences but nothing happens. Whatユs going on?
A: Changes to the slot settings wonユt occur until IIe is restarted. Hereユs how to change IIeユs slot settings:
1) change the settings in the Slots pane in the IIe Preferences window and click the OK button
2) select Quit IIe from the File menu
3) double click the IIe icon. IIe will then start up with the new slot settings.
Q: I have some Apple II disks. How do I get the programs to work with IIe?
A: If your disks are 3 1/2" disks, just run IIe and then insert the disk into the Macユs floppy drive. IIe will ask you which drive you want to insert it into. Select a drive and then the disk is accessible just like on a real //e. Note that this assumes that you have already installed the UniDisk/Hard Disk card into a slot (see the Slots Pane section in the メConfiguring IIeモ file for info on how to do this if you havenユt).
If your disks are 5 1/4" disks, then youユll need a real //e to transfer them to floppy disk or to a Mac via a serial connection. Please obtain the メcomp.emulators.apple2モ FAQ available on the internet for a detailed description of how to do this. And if youユre curious, the answer is メno, you canユt use a IBM-compatible PC to read Apple II 5 1/4" disksモ.
Q: How do I write Apple II programs?
A: You should be able to find a book on this topic from a library or bookshop. If not, ask your local user group or programming association. On the internet, post a (polite) message to the newsgroup news:comp.sys.apple2.programmer
Q: Why doesnユt //e program I wrote work the way I want it to?
A: Itユs beyond the scope of these documents to tell you how to program or what is wrong with it. See the answer to the last question for some resources that you can try.
Q: Where on the internet can I get the latest version of IIe from?
A: Use a World Wide Web browser to get it from:
http://www.usyd.edu.au/~victort/homepage.html
The latest version is always here. If you donユt have internet access, then try these suggestions:
・ ask someone who has access
・ use a メcybercafeモ
・ try a public library
・ try a BBS
・ ask your local user group
Q: Where on the internet can I find some Apple II software or information?
A: Try these places:
<ftp://ground.isca.uiowa.edu/> (hard to get in)
<telnet:ground.isca.uiowa.edu> (preferred method)
<ftp://ftp.hypermall.com/pub/apple2/> is a mirror of ground
<ftp://ftp.asimov.net/pub/apple_II/> (hard to get in)
<http://www.asimov.net/pub/apple_II> (much easier to get into)
<ftp://ftp.uni-kl.de/pub/apple2/> (can be hard to get in)
<ftp://apple2.caltech.edu/> (limited to 15 users, can also be accessed via gopher!)
<news:comp.emulators.apple2>
<news:comp.system.apple2>
I also recommend obtaining the document in this directory:
<http://www.asimov.net/pub/apple_II/FAQs/>
it contains useful information especially about transferring data from an Apple II to a Mac/PC.
Q: Why should I register IIe? After all, I have it now and can use it straight away.
A: IIe is released as shareware. Youユre free to try it out but if you decide to keep on using it, youユre obliged to register. After all, itユs a pretty good deal for you: you get the software and can use it without having to pay up front. Also, it isnユt crippled or disabled - so what you see is what you get! In return, I ask you to be honest about its use and pay the registration fee when you feel that you wish to keep the program.
Think about it from my point of view: this program was hard work. It wouldnユt exist unless someone put in the time and effort to write it and make it work well and as bug-free as possible. Itユs only fair that if a payment is requested then you pay for it if you think itユs worth it. Also, paying the fee is very encouraging for me and allows further development to be done.
On a final note, payment is a quick and simple thing to do. Please see the last document for details about how to do it.
Iユll conclude with this: メthank you for supporting sharewareモ.